The AGILE satellite operated from April 23, 2007 to January 18, 2024 observing thousands of astrophysical sources.
The AGILE spacecraft operated in "pointing mode" from the beginning of the mission to October 15, 2009, completing 101 observation blocks (OBs). The OBs usually consisted of predefined long exposures, drifting about 1 deg per day with respect to the initial boresight direction to obey solar panels constraints.
In November 2009, the attitude control system was reconfigured, and scientific operations were performed "spinning mode" until the end of the mission. AGILE scanned ≈ 80% sky daily (exposure of ≈ 7 · 106 cm2 s) with an angular velocity of about 0.8 deg s−1, performing 200 passes per day on the same sky region.
The visibility of a source thus depend on the off-axis angle with respect to the satellite pointing direction.
The purpose of this notebook is to show how to use the class AGVisibility to determine the AGILE pointing direction and the offset of a source of interest.
The class requires only the "log files", which are the AGILE spacecraft files, to perform its task.
If a Fermi Spacecraft file is provided, the same operation can be performed on the file for comparison purposes.
# Import the relevant class
from agilepy.api.AGVisibility import AGVisibility
from agilepy.utils.AstroUtils import AstroUtils
from astropy.coordinates import SkyCoord
from astropy.time import Time
This tutorial uses the available test dataset on blazar 3C 454.3, from 2010-11-13 to 2010-11-21 (MJD 55513-55521).
# Prepare the YAML Configuration File.
# You can create it manually or use AGVisibility.getConfiguration()
outputDir = "/home/flareadvocate/workspace/shared_dir/"
confFilePath = "/home/flareadvocate/workspace/shared_dir/tutorial_visibility.yaml"
logFile = "$AGILE/agilepy-test-data/test_dataset_agn/LOG/LOG.index"
fermi_SCFile = "$AGILE/agilepy-test-data/visibility/Fermi_test_SC00.fits"
AGVisibility.getConfiguration(
confFilePath=confFilePath,
# Output
outputDir=outputDir,
userName="my_name",
sourceName="vis-source",
verboselvl=0,
# Input
logFile=logFile,
fermiSpacecraftFile=fermi_SCFile,
# Selection
step=1,
timeType="tt",
tmin="null",
tmax="null",
# Source
coord1="null",
coord2="null",
frame="icrs",
)
The YAML file has the following sections and field:
output: common to all agilepy classes, sets the following output fields: outdir, filenameprefix, sourcename, username, verboselvlinput: input spacecraft files.logFile: path to the index file listing relevant AGILE log files to be extracted.fermiSpacecraftFile: the path to the Fermi spacecraft file. Optional.selection: arguments that define the timing of the information extracted.step: time interval in seconds between two consecutive points in the resulting table. Minimum accepted value: 0.1.timeType: the time format of tmin and tmax. AGILE seconds can be expressed as tt.tmin: inferior observation time limit to analize. If not set, default value is TT = 104371200 (2007-04-23 00:00:00)tmax: superior observation time limit to analize. If not set, default value is TT = 632620800 (2024-01-18 00:00:00)source: optional, include arguments to define the coordinates of the source used to compute the offset. The coordinates can also be set or changed when using the class. They are defined by:frame: reference frame for astropy.coordinates.SkyCoordcoord1, coord2: source coordinates in degrees.# Create the AGVisibility object
ag_vis = AGVisibility(confFilePath)
# Print Options
ag_vis.printOptions()
Log level set to WARNING and output to /home/flareadvocate/workspace/shared_dir/my_name_vis-source_20251005-231634/logs
{ 'input': { 'fermi_spacecraft_file': '/home/flareadvocate/agiletools/agilepy-test-data/visibility/Fermi_test_SC00.fits',
'logfile': '/home/flareadvocate/agiletools/agilepy-test-data/test_dataset_agn/LOG/LOG.index'},
'output': { 'filenameprefix': 'visibility_product',
'outdir': PosixPath('/home/flareadvocate/workspace/shared_dir/my_name_vis-source_20251005-231634'),
'sourcename': 'vis-source',
'username': 'my_name',
'verboselvl': 0},
'selection': { 'step': 1,
'timetype': 'TT',
'tmax': 632620800,
'tmin': 104371200},
'source': {'coord1': None, 'coord2': None, 'frame': 'icrs'}}
# You can use the setOptions() method to change the configuration:
# Set coordinates of 3C 454.3
ag_vis.setOptions(coord1=343.496, coord2=16.151, frame='icrs')
# Set time range appropriate for the test dataset
ag_vis.setOptions(tmin=AstroUtils.convert_time_to_agile_seconds(Time(55513, format='mjd')),
tmax=AstroUtils.convert_time_to_agile_seconds(Time(55521, format='mjd')),
timetype="TT"
)
# Check configuration
ag_vis.printOptions()
{ 'input': { 'fermi_spacecraft_file': '/home/flareadvocate/agiletools/agilepy-test-data/visibility/Fermi_test_SC00.fits',
'logfile': '/home/flareadvocate/agiletools/agilepy-test-data/test_dataset_agn/LOG/LOG.index'},
'output': { 'filenameprefix': 'visibility_product',
'outdir': PosixPath('/home/flareadvocate/workspace/shared_dir/my_name_vis-source_20251005-231634'),
'sourcename': 'vis-source',
'username': 'my_name',
'verboselvl': 0},
'selection': { 'step': 1,
'timetype': 'TT',
'tmax': 217382400.0,
'tmin': 216691200.0},
'source': {'coord1': 343.496, 'coord2': 16.151, 'frame': 'icrs'}}
Note on time conversion: the agilepy.utils.AstroUtils.AstroUtils class offers utility functions for the conversion between AGILE seconds and other data formats, handled through the astropy.time.Time class.
# Convert from AGILE seconds to astropy Time
t_example = AstroUtils.convert_time_from_agile_seconds(104371200)
display(f"TT=104371200 corresponds to MJD {t_example.mjd}, ISO {t_example.iso}, UNIX {t_example.unix}")
# Convert from astropy Time to AGILE seconds
t_example = AstroUtils.convert_time_to_agile_seconds(Time(54213, format='mjd'))
display(f"MJD=54213.0 corresponds to TT {t_example}")
'TT=104371200 corresponds to MJD 54213.0, ISO 2007-04-23 00:00:00.000, UNIX 1177286400.0'
'MJD=54213.0 corresponds to TT 104371200.0'
The AGILE pointing coordinates can be computed with AGVisibility.computePointingDirection().
The arguments of the function are taken by default from the configuration, or they can be overriden if provided explicitly as arguments of the method.
The AGILE data is extracted from the columns TIME, ATTITUDE_RA_Y, ATTITUDE_DEC_Y of the log files and stored in an astropy.table.Table.
The output columns provide the start and stop times of the bin analysed in TT and MJD, the AGILE pointing coordinates (Right Ascension and Declination) and the mean offset of the source in degrees in the bin.
The distance between two consecutive bins is the step parameter.
The table is saved by default in the agilepy output directory as a .csv file.
agile_visibility_table = ag_vis.computePointingDirection(writeFiles=True)
# Show
display(agile_visibility_table)
# Note: The table can also be accessed as a property of AGVisibility:
# ag_vis.agileVisibility
| TT_start | TT_stop | AGILE_RA | AGILE_DEC | MJD_start | MJD_stop | offaxis_angle_deg |
|---|---|---|---|---|---|---|
| float64 | float64 | float64 | float64 | float64 | float64 | float64 |
| 216691200.0 | 216691200.1 | 222.24676513671875 | 72.3887939453125 | 55513.0 | 55513.00000115741 | 83.43257364718369 |
| 216691201.0 | 216691201.1 | 219.79591369628906 | 72.32183837890625 | 55513.00001157408 | 55513.00001273148 | 84.07688376120517 |
| 216691202.0 | 216691202.1 | 217.36424255371094 | 72.22473907470703 | 55513.000023148146 | 55513.000024305555 | 84.72213619894937 |
| 216691203.0 | 216691203.1 | 214.96282958984375 | 72.09690856933594 | 55513.00003472222 | 55513.00003587963 | 85.36813315305827 |
| 216691204.0 | 216691204.1 | 212.5966033935547 | 71.93963623046875 | 55513.0000462963 | 55513.0000474537 | 86.01495135877619 |
| 216691205.0 | 216691205.1 | 210.27674865722656 | 71.75337982177734 | 55513.00005787037 | 55513.00005902778 | 86.66169258017244 |
| 216691206.0 | 216691206.1 | 208.0039520263672 | 71.53815460205078 | 55513.000069444446 | 55513.00007060185 | 87.31008697219828 |
| 216691207.0 | 216691207.1 | 205.79298400878906 | 71.29309844970703 | 55513.000081018516 | 55513.000082175924 | 87.95946833316754 |
| ... | ... | ... | ... | ... | ... | ... |
| 217382392.1 | 217382392.2 | 198.89260864257812 | 65.11902618408203 | 55520.999908564816 | 55520.999909722224 | 94.42071818104152 |
| 217382393.1 | 217382393.2 | 197.42193603515625 | 64.69849395751953 | 55520.999920138885 | 55520.999921296294 | 95.11427439693121 |
| 217382394.1 | 217382394.2 | 195.99659729003906 | 64.26290893554688 | 55520.99993171296 | 55520.99993287037 | 95.80856711789367 |
| 217382395.1 | 217382395.2 | 194.6165008544922 | 63.81315231323242 | 55520.99994328704 | 55520.99994444445 | 96.50327748643129 |
| 217382396.1 | 217382396.2 | 193.27850341796875 | 63.35227966308594 | 55520.99995486111 | 55520.99995601852 | 97.1967921444698 |
| 217382397.1 | 217382397.2 | 191.98133850097656 | 62.878910064697266 | 55520.999966435185 | 55520.999967592594 | 97.89085242403705 |
| 217382398.1 | 217382398.2 | 190.73019409179688 | 62.39262771606445 | 55520.999978009255 | 55520.99997916667 | 98.58504254443122 |
| 217382399.1 | 217382399.2 | 189.52203369140625 | 61.8945198059082 | 55520.99998958333 | 55520.99999074074 | 99.27936207655596 |
The Fermi pointing coordinates can be computed with AGVisibility.getFermiPointing().
The arguments of the function are taken by default from the configuration, or they can be overriden if provided explicitly as arguments of the method.
The Fermi data is extracted from the columns START, STOP, RA_SCZ, DEC_SCZ of the spacecraft file and stored in an astropy.table.Table.
The output columns provide the start and stop times of the bin analysed in TT, MJD, Fermi MET seconds, the Fermi pointing coordinates (Right Ascension and Declination) and the mean offset of the source in degrees in the bin.
The table is saved by default in the agilepy output directory as a .csv file.
fermi_visibility_table = ag_vis.getFermiPointing(writeFiles=True)
# Show the table, accessed as a property of AGVisibility:
display(ag_vis.fermiVisibility)
WARNING: UnitsWarning: 'Gauss' did not parse as fits unit: At col 0, Unit 'Gauss' not supported by the FITS standard. If this is meant to be a custom unit, define it with 'u.def_unit'. To have it recognized inside a file reader or other code, enable it with 'u.add_enabled_units'. For details, see https://docs.astropy.org/en/latest/units/combining_and_defining.html [astropy.units.core] WARNING: UnitsWarning: 'Earth_Radii' did not parse as fits unit: At col 0, Unit 'Earth_Radii' not supported by the FITS standard. If this is meant to be a custom unit, define it with 'u.def_unit'. To have it recognized inside a file reader or other code, enable it with 'u.add_enabled_units'. For details, see https://docs.astropy.org/en/latest/units/combining_and_defining.html [astropy.units.core]
| MET_START | MET_STOP | RA_SCZ | DEC_SCZ | TT_start | TT_stop | MJD_start | MJD_stop | offaxis_angle_deg |
|---|---|---|---|---|---|---|---|---|
| s | s | deg | deg | |||||
| float64 | float64 | float32 | float32 | float64 | float64 | float64 | float64 | float32 |
| 311299218.6 | 311299248.6 | 266.66574 | 70.37467 | 216691218.60000002 | 216691248.60000002 | 55513.000215277774 | 55513.0005625 | 70.39624 |
| 311299248.6 | 311299278.6 | 269.59912 | 69.69561 | 216691248.60000002 | 216691278.60000002 | 55513.0005625 | 55513.00090972222 | 69.30859 |
| 311299278.6 | 311299308.6 | 272.3954 | 68.99575 | 216691278.60000002 | 216691308.60000002 | 55513.00090972222 | 55513.001256944444 | 68.210075 |
| 311299308.6 | 311299338.6 | 275.06284 | 68.274506 | 216691308.60000002 | 216691338.60000002 | 55513.001256944444 | 55513.00160416667 | 67.1011 |
| 311299338.6 | 311299368.6 | 277.61572 | 67.53844 | 216691338.60000002 | 216691368.60000002 | 55513.00160416667 | 55513.00195138889 | 65.98142 |
| 311299368.6 | 311299398.6 | 280.05908 | 66.78771 | 216691368.60000002 | 216691398.60000002 | 55513.00195138889 | 55513.00229861111 | 64.85262 |
| 311299398.6 | 311299428.6 | 282.4037 | 66.0241 | 216691398.60000002 | 216691428.60000002 | 55513.00229861111 | 55513.00264583333 | 63.714382 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 311988676.6 | 311988706.6 | 321.14102 | 25.867832 | 217380676.60000002 | 217380706.60000002 | 55520.98005324074 | 55520.98040046296 | 22.9716 |
| 311988706.6 | 311988736.6 | 322.45694 | 25.6432 | 217380706.60000002 | 217380736.60000002 | 55520.98040046296 | 55520.980747685186 | 21.785173 |
| 311988736.6 | 311988766.6 | 323.77426 | 25.435379 | 217380736.60000002 | 217380766.60000002 | 55520.980747685186 | 55520.98109490741 | 20.606659 |
| 311988766.6 | 311988796.6 | 325.0935 | 25.246605 | 217380766.60000002 | 217380796.60000002 | 55520.98109490741 | 55520.981442129625 | 19.43865 |
| 311988796.6 | 311988824.085537 | 326.4125 | 25.07553 | 217380796.60000002 | 217380824.08553702 | 55520.981442129625 | 55520.98176024927 | 18.285112 |
| 311990302.64574337 | 311990332.6 | 86.6461 | -48.26763 | 217382302.64574337 | 217382332.60000002 | 55520.99887321462 | 55520.999219907404 | 110.67387 |
| 311990332.6 | 311990362.6 | 88.04295 | -47.49842 | 217382332.60000002 | 217382362.60000002 | 55520.999219907404 | 55520.99956712963 | 111.59731 |
| 311990362.6 | 311990392.6 | 89.429375 | -46.734695 | 217382362.60000002 | 217382392.60000002 | 55520.99956712963 | 55520.99991435185 | 112.53722 |
AGVisibility offers an utility function to plot the time series of the Offaxis angle.
Parameters are:
sourceCoordinates (astropy.coordinates.SkyCoord): the coordinates of the source used to compute the offaxis angle, If None, the offaxis angle must already be computed in the visibility table.maxOffaxis (float): maximum offaxis angle in degrees to be shown in the visibility plot.mjd_limits (tuple(float,float), optional): Plot limits in MJD.plotFermi (bool): if True, plot the Fermi offaxis angle.plotHistogram (bool): if True, plot the histogram of the offaxis angles.saveImage (bool): if True, save the images in the output directory.showPositionPanels (bool): if True, show the RA and DEC time series of the satellite direction.# Plot
ag_vis.plotVisibility(mjd_limits=(55519, 55519.5), maxOffaxis=60,
plotFermi=True, plotHistogram=True, saveImages=True,
showPositionPanels=False
)
[PosixPath('/home/flareadvocate/workspace/shared_dir/my_name_vis-source_20251005-231634/plots/offaxis_ra343.4960_+16.1510.reg_MJD_55519_55519.5.png'),
PosixPath('/home/flareadvocate/workspace/shared_dir/my_name_vis-source_20251005-231634/plots/offaxis_hist_ra343.4960_+16.1510.reg_MJD_55519_55519.5.png')]